home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / clipper / subntx2.zip / SUBNTX.DOC < prev    next >
Text File  |  1990-05-24  |  20KB  |  463 lines
  1.                                      --------
  2.                                      SUBNTX()
  3.                                      --------
  4.  
  5.                               Version 2.00 -  5/24/90
  6.  
  7.                       Copyright 1989, 1990 Moon Microsystems
  8.  
  9.      INTRODUCTION:
  10.  
  11.           Subntx() is a C function called from a Clipper program to quickly
  12.           extract index elements from an existing index file, and create a
  13.           "subset" index matching some key.
  14.  
  15.           Typical uses for SubNtx() include implementing a 'WHILE' clause for
  16.           dbedit, replacing or deleting groups of records, or reporting for a
  17.           certain condition.  Any of these processes can be made to perform
  18.           significantly faster with SubNtx().
  19.  
  20.  
  21.      SYNTAX:
  22.  
  23.           result_code = subntx( <main>,<sub>,<lkey>
  24.                [,<ukey> [,<pattern> [,<use_extproc> [,<num_tries_to_lock]]]])
  25.  
  26.      WHERE:
  27.  
  28.      <main> - is a character string (including the ".ntx" extension) or
  29.           character variable which contains the name of the existing index
  30.           from which keys are to be extracted.  It will be opened in SHARED
  31.           mode if on a network.  (To be sure that buffers are flushed to disk,
  32.           the <main> index should be closed via the SET INDEX TO command.  (I
  33.           have heard that when a file is opened in SHARED mode, it is flushed
  34.           to disk after each write. Be careful though and check this out
  35.           yourself if you decide to not SET INDEX TO).
  36.  
  37.      <sub> - is also a character string (with the ".ntx" extension) or
  38.           variable which contains the name of the 'SUB' index to be created.
  39.           It will overwrite any file with the same name.
  40.  
  41.      <lkey> - is a character string or character variable which contains the
  42.           string that is compared to the keys of the <main> index.  SubNtx()
  43.           is like a SEEK key with SET EXACT OFF in that it will include
  44.           partial matches in the new sub index.  Example: "Moo" will match
  45.           "Moon".
  46.  
  47.           <lkey> is the lower range when an optional upper range key
  48.           (discussed next) is used.
  49.  
  50.           If <lkey> contains the single character '*', it will match any key
  51.           up to and including the <ukey>, if an upper key exists, otherwise it
  52.           will attempt to match everything.
  53.  
  54.           Note:  The '*' character in <lkey> is converted to a "" which will
  55.           match anything just as SEEK would normally.  You may just use "" if
  56.           you wish but this option is added to be consistent with the same
  57.           feature of the <ukey> which MUST contain '*' to be infinite.
  58.  
  59.      <ukey> - is an optional parameter which, if not an empty string "", will
  60.           be used as the upper boundary for a range.  Again, partial matches
  61.           are included in the new subset index, so a range of:  lkey="Loon",
  62.           ukey="Mo" will match a <main> index key of "Moon".
  63.  
  64.           <ukey> can consist of the empty string "" if you don't want an upper
  65.           range but you want to use one of the other optional parameters.
  66.  
  67.           <ukey> can also contain the single character '*' to indicate that
  68.           there is an infinite upper bound.  This will attempt to cause a
  69.           match of the <lkey> and all keys above it.  If you attempt to place
  70.           other characters after a '*' in either the <lkey> or <ukey>, they
  71.           will just be ignored.
  72.  
  73.      <pattern> - is an optional character string or variable which may consist
  74.           of a combination of literal characters and  spaces, zero or more
  75.           occurrences of '?', and zero or more occurrences of '*'.  <pattern>
  76.           is similar to the DOS wildcard expressions with some exceptions.
  77.  
  78.           <pattern> is tested against each key which matches or falls in the
  79.           range of <lkey> to <ukey>.  Note that it does not waste time
  80.           comparing keys which fall outside the range, but of course an
  81.           infinite range could be specified which would then compare all keys
  82.           to the wildcard pattern.
  83.  
  84.           Just as in DOS, a literal character will match itself, and '?' will
  85.           match ANY single character in that key position.  Also as in DOS,
  86.           '*' will match zero or more of ANY combination of characters.
  87.  
  88.           One difference with the SubNtx() <pattern> is that the pattern will
  89.           enable an exact match (as opposed to a partial match in the <lkey>
  90.           and <ukey>) unless the '*' is the last character in the pattern.  A
  91.           list of examples follow:
  92.  
  93.  
  94.  
  95.           INDEX KEY            PATTERN        RESULT
  96.           ----------------     -----------    ------
  97.           "Color of Money "    "Col*"         TRUE
  98.           "Color of Money "    "*Col*"        TRUE
  99.           "Color of Money "    "*ey "         TRUE
  100.           "Color of Money "    "*ey"          FALSE
  101.           "Color of Money "    "* *"          TRUE
  102.           "Color of Money "    "Color"        FALSE
  103.           "Color of Money "    "*of*"         TRUE
  104.           "Color of Money "    "*OF*"         FALSE
  105.           "Color of Money "    "?ol*"         TRUE
  106.           "Color of Money "    "*?ol*"        TRUE
  107.           "Color of Money "    "??lor M*"     TRUE
  108.           "Color of Money "    "*Mo?ey??"     FALSE
  109.           "Color of Money "    "*Mo?ey*"      TRUE
  110.           "Color of Money "    "*Mo?ey"       FALSE
  111.  
  112.      <use_extproc> - This is an optional logical (.T. OR .F.) parameter which,
  113.           if passed to SubNtx(), signals for SubNtx() to call a Clipper
  114.           procedure named _subeval when an index key matches or is in the
  115.           range of <lkey> to <ukey>.  This procedure can determine if the key
  116.           is extracted into the sub index or not.
  117.  
  118.           If the developer uses this flag, he/she must create a procedure
  119.           named _subeval() and must return a logical value back by using a
  120.           SubNtx() internal function: reteval( <true_or_false> ).  If .t. is
  121.           returned, the current key in the index will be included in the new
  122.           sub index.
  123.  
  124.           (The value returned with reteval is actually stored in a C static
  125.           variable so that when _subeval returns to SubNtx() the result can be
  126.           evaluated.  If reteval() isn't called before _subeval is finished,
  127.           an undetermined random value will mistakenly be used in the
  128.           evaluation.)
  129.  
  130.           Two other SunNtx() internal functions which are available to
  131.           _subeval are: subrec() and subkey().  They return the current index
  132.           record number and key value, respectively.  A typical example of
  133.           creating  _subeval follows:
  134.  
  135.  
  136.           condition = "rec > 100 .and. inv_date > [04/22/90]"
  137.  
  138.           PROCEDURE _SUBEVAL
  139.                * Note no parameters
  140.                rec = subrec()
  141.                key = subkey()  && Not used in this example
  142.                GOTO rec
  143.                reteval( &condition )
  144.           RETURN
  145.  
  146.           ...OR...Use a CodeBlock for the condition in Clipper 5.0
  147.  
  148.           Note:  To prevent an unresolved external error when not using the
  149.           _subeval procedure, there is a C function with the same name in the
  150.           SubNtx() library which just returns true.  For this reason you may
  151.           get a warning about duplicate symbols, but this can be ignored.  The
  152.           procedure in your code will take precedence.
  153.  
  154.           Also note that using the _subeval procedure may slow down SubNtx()
  155.           considerably, due to the overhead of reading in the actual DBF
  156.           record.  If only the subkey() is evaluated, it is much faster.
  157.           Either way it is probably much faster than reindexing or using a
  158.           conditional index since the sorting process has already been done
  159.           when the main index was created.
  160.  
  161.      <num_tries_to_lock> - is an optional paramter which indicates the number
  162.           of times SubNtx() should try to lock the main index file for
  163.           reading.  If no value is passed, the default is to try 3 times, once
  164.